## 18.2. Lite

Lite is the scripting language used by W3-mSQL. In syntax, it is similar to C and even more to Perl. In fact, many Lite scripts are syntactically indistinguishable from Perl scripts. Lite, however, lacks many of the advanced features of Perl.

Below is a quick reference of the standard Lite functions that are available when using W3-mSQL.

chdir |

    $result = chdir($path)

Changes directory to the specified path. If the operation is unsuccessful, a negative integer is returned.

chmod |

    $result = chmod($filename, $mode)

Changes the mode of the specified file to `mode`. If the operation is unsuccessful, a negative integer is returned. The value `mode` can be given as a decimal, octal or hexadecimal value.

chop |

    $string = chop($string)

Returns the string with the last character removed. This is handy for removing newlines from the end of strings read with `readln`.

close |

    close ($fd)

Closes the file associated with the file descriptor.

ctime |

    $time = ctime($time)

Converts `time`, which is some number of seconds since the epoch, into the common Unix text representation of the time.

echo |

    FM-Command>echo($string)

Prints the given string. Any variables in the string will be replaced with the values of the variables.

fprintf |

    fprintf($fd, $string [, arg ...])

Works like the C (or Perl) function of the same name. The first argument is a file descriptor. The formatted string is printed to the file associated with the file descriptor.

gethostbyaddr |

    $hostinfo = gethostbyaddr($address)

Returns the same array as `gethostbyname()` for given IP number. The IP should be given as a decimal string, as in "127.0.0.1". In the official W3-mSQL documentation, this function is referred to as both `gethostbyaddr` and `gethostbyaddress`. At the time of this writing `gethostbyaddress` is incorrect and does not exist as a function in W3-mSQL.

gethostbyname |

    $hostinfo = gethostbyname($host)

Returns an array of information about the given host. The first element of the array is the name of the host and the second is the IP number.

getpid |

    $pid = getpid()

Returns the process ID of the Lite program.

getpwnam |

    $entry = getpwnam($username)

Returns an array of information about the user with the username `username`. The fields of the array are as follows:

1. Username

2. Password

3. UID

4. GID

5. GECOS (Full name and other optional information)

6. Home directory

7. Shell

getpwuid |

    $entry = getpwuid($UID)

Returns an array identical to that of `getpwnam` for the user with the user ID `$UID`.

includeFile |

    includeFile($filename)

This function includes the file `filename` into the output of the program. The file is not modified or parsed in any way.

kill |

    $result = kill($pid, $signal)

Sends the signal `signal` to the process `pid`. If the operation is unsuccessful, a negative integer is returned.

link |

    $result = link($file, $newlinkname)

Creates a `hard' link from `file` to `newlinkname`. If the operation is unsuccessful, a negative integer is returned.

mkdir |

    $result = mkdir($directoryname)

Creates a directory with the given name. If the operation is unsuccessful, a negative integer is returned.

msqlConnect |

    $socket = msqlConnect($host)

Connects to the mSQL server on the host `host`. The return value is the socket number used in a subsequence communication with the database server. If unsuccessful, a negative integer is returned.

msqlClose |

    msqlClose($socket)

Terminates the connection identified by `socket`.

msqlDataSeek |

    msqlDataSeek($result, $location)

This places the `pointer' for `result` immediately before the row `location`. Setting the location to `0` puts the pointer at the beginning of the data. The next call to `msqlFetchRow` will retrieve the row after `location`.

msqlEncode |

    $string = msqlEncode($string)

This function returns a copy of `string` that is safely encoded for use in a mSQL query.

msqlFetchRow |

    $row = msqlFetchRow($result)

This function returns the next row of available data in `result` as an array.

msqlFieldSeek |

    msqlFieldSeek($result, $location)

This changes the `pointer' of a result generated by `msqlInitFieldList` in the same way that `msqlDataSeek` effects results from `msqlStoreResult`.

msqlFreeResult |

    msqlFreeResult($result)

This frees any memory used by a result retrieved with `msqlStoreResult`. This function must be called for each result when you are finished with it.

msqlInitFieldList |

    $result = msqlInitFieldList($socket, $database, $table)

This creates a table of information about the table `table` in the database `database` on the server indicated by `socket`.

msqlListDBs |

    $databases = msqlListDBs($socket)

Returns an array of the names of all of the databases available on the server indicated by `socket`.

msqlListField |

    $tableinfo = msqlListField($result)

Returns an array of information about the next field in the table generated from `msqlInitFieldList`, indicated by `result`. Each successive call to `msqlListField` produces a new array until there are no more fields left. The array consists of the following fields:

0

  Field Name

1

  Table Type

2

  Type

3

  Length

4

  Flags

msqlListTables |

    $tables = msqlListTables($socket, $database)

Returns an array of the names of the tables available on `database` on the server indicated by `socket`.

msqlNumRows |

    msqlNumRows($result)

Returns the number of rows of data contained in the result `result`.

msqlQuery |

    $result = msqlQuery($socket, $query)

This attempts to send to query `query` to the connection `socket`. If the query was not successfully executed, a negative integer is returned.

msqlSelectDB |

    $result = msqlSelectDB($socket, $database)

This function attempts to set the connection `socket` to use the database `database`. If unsuccessful, a negative integer is returned.

msqlStoreResult |

    $result = msqlStoreResult

Retrieves any data that was produced by the last `msqlQuery` call and stores it for access and manipulation.

open |

    $fd = open($file, $mode)

This function opens the given file using the given mode and associates a file descriptor with the file. The defined modes are as follows:

>

  Open the file for writing.

<

  Open the file for reading.

<>

  Open the file for reading or writing.

<P

  Create a named pipe and open it for reading.

>P

  Create a named pipe and open it for writing.

<|

  Execute the file as a command and read the output.

>|

  Execute the file as a command and write to the process.

pid |

    $pid = getppid()

Returns the process ID of the process that is the parent of the Lite program.

printf |

    printf($string [, arg, ... ])

This works like the C (or Perl) function of the same name. Variables in the string are not substituted; standard C ``%s`' format must be used to insert variables into the string.

read |

    $data = read($fd, $length)

Read `length` number of bytes from the specified file descriptor.

readln |

    $line = readln($fd)

Read the next line from the specified file descriptor.

readtok |

    $data = readtok($fd, $token)

Read data from the specified file descriptor until the token is encountered. Only the first character of `token` is used.

rename |

    $result = rename($oldname, $newname)

This attempts to rename of the specified file (or directory) from `oldname` to `newname`. If the operation is unsuccessful, a negative integer is returned.

rmdir |

    $result = rmdir($path)

This attempts to remove the given directory. If the operation is unsuccessful, a negative integer is returned.

setContentType |

    setContentType($string)

This function overrides the default content type of HTML page containing the script and uses `string` in its place. This function must be the very first line in the document to work. Not even a blank line can precede it.

sleep |

    sleep($time)

This stops the program for `time` number of seconds.

split |

    $strings = split($string, $token)

Splits the given string by the token character into an array of strings.

stat |

    $stat = stat($file)

Returns an array of information about `file`. The elements of the array are as follows:

1. Inode number

2. File mode

3. Number of links to file

4. UID

5. GID

6. Size of file

7. Atime

8. Mtime

9. Ctime

10. Block size of file system (in bytes)

11. Number of file system block used

strftime |

    $time = strftime($format, $time)

This converts a Unix time into a text representation of the time using `format` as a guide. Any of the following sequences in `format` are replaced with their corresponding value:

%a

  Day of week, using locale's abbreviated weekday names

%A

  Day of week, using locale's full weekday names

%b

  Month, using locale's abbreviated month names

%B

  Month, using locale's full month names

%d

  Day of month (01-31)

%D

  Date as %m/%d/%y

%e

  Day of month (1-31 with single digits preceded by a space)

%H

  Hour (00-23)

%I

  Hour (00-12)

%j

  Day of year (001-366)

%k

  Hour (0-23, blank padded)

%l

  hour (1-12, blank padded)

%m

  Month number (01-12)

%M

  Minute (00-59)

%p

  AM or PM

%S

  Seconds (00-59)

%T

  Time as %H:%M:%S

%U

  Week number in year (01-52)

%w

  Day of week (0-6, Sunday being 0)

%y

  Year within the century (00-99)

%Y

  Year including century (e.g., 1999)

strseg |

    $string = strseg($string, $start, $end)

Returns the substring of the given string which starts at `start` characters and ends at `end` characters from the beginning of the string.

sub |

    $string = sub($string, $expr1, $expr2)

This substitutes any occurrences of `expr1` in `string` with `expr2`. The values of `expr1` and `expr2` may differ in length; `string` will be lengthened or shortened automatically.

substr |

    $string = substr($string1, $regexp, $string2)

This finds the substrings of `string1` that match the regular expression `regexp`. For each part of the regular expression enclosed in parenthesis that matches, the corresponding variable `$1`, `$2`, `$3`, etc. is set with the value of the match. The value of `string2` is returned with variables (including `$1`, `$2`, `$3`, etc.) expanded.

symlink |

    $result = symlink($file, $newlinkname)

This attempts to create a symbolic link from `file` to `newlinkname`. This function is only supported on some operating systems. If the operation is unsuccessful, a negative integer is returned.

system |

    $result = system($command)

This function spawns a shell and executes `command`. Any output of the command is redirected to the output of the program.

test |

    $result = test($test, $filename)

This performs the test `test` on the file `filename`. If the test is successful, 1 is returned, otherwise is returned. The available tests are as follows:

b

  Block mode device

c

  Character mode device

d

  Directory

p

  Named pipe

s

  Nonempty regular file

f

  Regular file

u

  Setuid file

g

  Setgid file

time |

    $time = time()

Returns the number of seconds since the epoch (00:00:00 GMT, Jan. 1, 1970).

time2unixtime |

    $time = time2unixtime($sec, $min, $hour, $day, $month, $year)

This converts the values for a time into the Unix form of the time (which is the number of seconds since the epoch).

tr |

    $string = tr($string, $list1, $list2)

Substitutes all of the characters in `list1` that exist in `string` with the equivalent character in `list2` (e.g.,`tr(`"`Robby","oy","ai")` would return the string "Rabbi"). The list of characters can contain a range of characters separated with `"-"`. For instance, `tr("e.e. cummings", "a-z," "A-Z")` will return the string "E.E. CUMMINGS."

truncate |

    $result = truncate($file, $length)

This attempts to truncate the given file to `length` bytes. This is usually used to create a zero-length file. If the operation is unsuccessful, a negative integer is returned.

umask |

    umask($mask)

This sets the umask of the current process to `mask`. The value `mask` can be given in decimal, octal, or hexadecimal.

unixtime2* |

    $year = unixtime2year($time)
    $month = unixtime2month($time)
    $day = unixtime2day($time)
    $hour = unixtime2hour($time)
    $min = unixtime2min($time)
    $sec = unixtime2sec($time)

These functions take a Unix time value and return the requested value. For example, `unixtime2day(time())`, would return the current day of the month (a value between 1 and 31).

unlink |

    $result = unlink("filename")

This deletes the specified file. If the operation is unsuccessful, a negative integer is returned.

urlEncode |

    $string = urlEncode($string)

This function returns a copy of `string` that is safely encoded for insertion into a URL.

Copyright © 2001 O'Reilly & Associates. All rights reserved.